home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: MegaDisc / MegaDisc 29 (1992-07)(MegaDisc Digital Publishing)(AU)(Disk 1 of 2)[WB].zip / MegaDisc 29 (1992-07)(MegaDisc Digital Publishing)(AU)(Disk 1 of 2)[WB].adf / Programming / Asm_Startup / Startup_doc < prev    next >
Text File  |  1992-08-04  |  7KB  |  230 lines
  1.  
  2.  
  3.                    startup.o
  4.                    parsecommandline.o
  5.  
  6.                Copyright © 1992 Michael McCallum
  7.  
  8.  
  9.    <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< 29 >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  10.  
  11.  
  12. WHAT'S HERE
  13.  
  14. You should find here:
  15.  
  16.     1.  startup.doc  (this file)
  17.     2.  startup.o  (the linkable startup code for your programs!)
  18.     3.  parsecommandline.o  (separate parser, for those that want it)
  19.  
  20.  
  21. INFORMATION
  22.  
  23.    Before I get into the detailed description, etc., I'll make it clear now:
  24.  
  25.     This is specifically aimed at the assembly language programmer!
  26.  
  27. Now, The Details!
  28.  
  29.    I created this because I want to write utilities and things in assembly
  30.   language, and I wanted the command line to be pre-processed.  Also, I only
  31.   needed CLI support.  If this is what you are looking for, then you are in
  32.   the right place!  Oh yeah, if you want to use the parser yourself, I have
  33.   provided the parser separately also.
  34.  
  35.    What you now have in your hands, is an alternative startup code module
  36.   that you may use instead of Commodere's standard startup code.  It is
  37.   intended for those CLI utilities and things that you write that do not need
  38.   WorkBench support, but need (relatively) intelligent command line parsing.
  39.   First off, I will not say that this is the be-all and end-all of startup
  40.   code.  However, here is a list of its features:
  41.  
  42.     + Small (only about 316 bytes, including parser!)
  43.     + Pre-parses the command line (wow!)
  44.     + Options (of the form "-x") are separated from normal parameters
  45.     + Pure code (can be made resident!!!)
  46.     + The parser is also available to be called by the main program
  47.  
  48.    To "use" the startup code, just link with this startup instead of
  49.   Commodore's startup.
  50.  
  51.  
  52. USING THE STARTUP
  53.  
  54.    When executed, the startup code checks for WorkBench execution.  If it has
  55.   been executed by WorkBench, then the startup simply gets and returns the
  56.   WBmessage, and drops out.
  57.  
  58.    If we get as far as realising we are a CLI process, then the command line
  59.   will be parsed, and then "main" will be called.
  60.  
  61.    Simple really!  Note, however, that Dos is not opened.  This must be done
  62.   by your "main" code, if you need Dos.  This is done so that the code is
  63.   capable of being made "resident".
  64.  
  65.  
  66.    Now, let's have a look at what the startup code passes to your "main"
  67.   code:
  68.  
  69.     main (parv,parc,optv,optc)
  70.            A0   D0   A1   D1
  71.  
  72.     A0: pointer to an argv-style array holding all non-option parameters
  73.     D0: the number of non-option parameters found
  74.     A1: pointer to an argv-style array holding all option parameters
  75.     D1: the number of option parameters found
  76.  
  77.    Note: nothing is passed via the stack!  I didn't design this stuff for C
  78.   programmers, you know!  They already have their arguments separated, where
  79.   us assembly language programmers must do it ourselves.  Here's to you, my
  80.   chums!
  81.  
  82.    The arrays pointed to by A0 and A1 are terminated with a zero, making
  83.   (Ax)+ scanning of parameters and options easy.  Also, the options have had
  84.   their "-" character stripped.
  85.  
  86.    The memory used for the command-line is allocated and freed automatically
  87.   by the startup code.
  88.  
  89.  
  90. THE PARSER
  91.  
  92.    The parser is also provided separately, if you don't want to use my
  93.   alternative startup code, but still want the parser.
  94.  
  95.    To use the parser, just include parsecommandline.o in your link line.
  96.  
  97.    Using the parser is pretty simple.  First, some definitions:
  98.  
  99. Parameters:     A parameter is a sequence of characters separated by spaces.
  100. Options:    An option is a parameter beginning with a minus sign (-).
  101.         Options are placed in a separate array from parameters,
  102.         without their option specifier (-).  This makes for easy
  103.         position-independent parsing of options.  How you use them
  104.         is up to you!
  105. Spaces:     Spaces are used to separate parameters and options.
  106. Quoting:    When the parser encounters a quote (") on the command line,
  107.         it ceases to interpret special characters, including spaces
  108.         and the escape character, until it reaches another quote.
  109. Escaping:       To escape a character, precede it with a backslash (\), and
  110.         no interpreting of the character will be done.  This can be
  111.         used to create a quote or space in a parameter.  Escaping
  112.         and quoting also work on the option specifier (-),
  113.         allowing a parameter to begin with a minus sign.
  114.         Eg: [\-foo] or ["-foo"].
  115. Control:    A control character ($01-$1F) can be generated by
  116.         preceding the character which represents it with a
  117.         caret (^) character.  Eg: [^j] will become control-j,
  118.         or linefeed ($0A).  An actual control character in the
  119.         command line will be completely ignored.
  120.         Eg: [abc<TAB>def] will become [abcdef].
  121.  
  122.  
  123. Big Example!
  124.  
  125. The command line
  126.  
  127.     -foo name1 \-name2 -bar "name 3"
  128.  
  129. will become:
  130.  
  131.     Parameter array (A0):    ("->" means "pointer to")
  132.       ->"name1",0
  133.       ->"-name2",0
  134.       ->"name 3",0
  135.       0
  136.  
  137.     Option array (A1):
  138.       ->"foo",0
  139.       ->"bar",0
  140.       0
  141.  
  142.    Note that the strings are zero terminated, as are the parameter and option
  143.   arrays themselves.  This makes it easy to parse option using the "(An)+"
  144.   processor addressing mode.
  145.  
  146.    Here is what you must pass to the parser:
  147.  
  148.     ParseCommandLine (cline,clinelen,stringbuff,parambuff,optionbuff);
  149.                A0      D0        A1        A2         A3
  150.  
  151.     A0: command line
  152.     D0: command line length
  153.     A1: buffer for parsed strings
  154.     A2: pointer to an argv-style array to hold all non-option parameters
  155.     A3: pointer to an argv-style array to hold all option parameters
  156.  
  157. ParseCommandLine returns:
  158.  
  159.     A0: pointer to an argv-style array holding all non-option parameters
  160.     D0: the number of non-option parameters found
  161.     A1: pointer to an argv-style array holding all option parameters
  162.     D1: the number of option parameters found
  163.  
  164.    IE: the same as what is passed to "main" by the startup code!
  165.  
  166.    When your main code is called, the memory for the parameters, options and
  167.   bits is allocated for you, but should you call ParseCommandLine yourself,
  168.   you will have to allocate your own memory.
  169.  
  170.    By the way, the code for the parser is only 150 bytes!
  171.  
  172.  
  173.  
  174. HOW TO
  175.  
  176.    Just use this startup.o instead of Commodore's.  Eg:
  177.  
  178.     BLink FROM startup.o,mymaincode.o LIB Amiga.lib TO MyProgram
  179.  
  180.    If you just want the parser:
  181.  
  182.     BLink FROM astartup.o,mymaincode.o,parsecommandline.o
  183.         LIB Amiga.lib TO MyProgram
  184.  
  185.  
  186.  
  187. COPYRIGHT
  188.  
  189.    This software is 100% my own work, and is copyright by me.  However, I
  190.   give one and all the rights to copy and distibute this software as long as:
  191.  
  192.     1.  It is unmodified
  193.     2.  It has it's documentation with it (this file).
  194.     3.  Only a minimal fee, if any, be charged for media and time.
  195.  
  196.    Also, this code may NOT be used in any commercial product without the
  197.   express permission of The Author (Michael McCallum).
  198.  
  199.  
  200. FINAL WORDS
  201.  
  202.    While I don't ask that you send me loadsadosh for this great wizz-bang bit
  203.   of contortery (is there such a word?), I am a student, and won't say no to
  204.   any contributions of money, disks, hardware, software, etc. that you nice
  205.   people want to send to me!  (No bombs or such, please!)  If you have any
  206.   comments, suggestions, or wicked jokes, send them to the address below!
  207.  
  208.  
  209. ME
  210.  
  211. I can be contacted thus:
  212.  
  213.     Michael McCallum
  214.     117 Morrison Rd
  215.     Midland WA 6056
  216.  
  217.     or
  218.  
  219.     09-274-3390
  220.  
  221.  
  222. Thank you, and enjoy!
  223.  
  224.  
  225.  
  226.    <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< 29 >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  227.  
  228.  
  229.  
  230.